<!--
 ~ Copyright (c) 2005-2010, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
 ~
 ~ WSO2 Inc. licenses this file to you under the Apache License,
 ~ Version 2.0 (the "License"); you may not use this file except
 ~ in compliance with the License.
 ~ You may obtain a copy of the License at
 ~
 ~    http://www.apache.org/licenses/LICENSE-2.0
 ~
 ~ Unless required by applicable law or agreed to in writing,
 ~ software distributed under the License is distributed on an
 ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~ KIND, either express or implied.  See the License for the
 ~ specific language governing permissions and limitations
 ~ under the License.
 -->
<!DOCTYPE html 
        PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
    <title>Business Process Component User Guide</title>
    <link href="../../admin/css/documentation.css" rel="stylesheet" type="text/css" media="all"/>
    <style type="text/css">
        img{
            padding:20px;            
        }
    </style>
</head>
<body style="width:1024px">
<h1>WSO2 BPEL Component User Guide</h1>
<h2>Introduction</h2>

<p>WSO2 Business Process commponent adds the capability to execute business processes written using WS-BPEL standard in
    WSO2 SOA platform. It also provides a complete web based graphical console to deploy, manage and view
    processes and process instances. WSO2 Business Process component is powered by
    Apache ODE(Orchestration Director Engine).
</p>

<h3>WS-BPEL</h3>

<p><a href="http://docs.oasis-open.org/wsbpel/2.0/OS/wsbpel-v2.0-OS.html" target="_blank">WS-BPEL</a> defines a
    language for the specification of Executable and Abstract business processes.
    By doing so, it extends the Web Services interaction model and enables it to support business transactions.
    WS-BPEL defines an interoperable integration model that should facilitate the expansion of automated process
    integration in both the intra-corporate and the business-to-business spaces. Processes in WS-BPEL export and import
    functionality by using Web Service interfaces exclusively.
</p>

<h2>Deploying BPEL Package</h2>

<h3>BPEL Package Format</h3>

<p>BPEL package is a ZIP archived directory with all the relevant deployment artifacts. Minimal BPEL package contains
    the deployment descriptor, one or more process definitions(.bpel or .cbp), WSDL and XSDs(excluding the ones compiled
    into .cbp). The deployment descriptor is a file named deploy.xml. To deploy, just copy the BPEL package containing
    your artifacts to the %CARBON_HOME%/repository/bpel directory. If you are using a URL repository copy the package to
    'bpel' direcotry in that repository.
</p>

<p>Folder structure of BPEL Package:</p>

<p><strong>BPEL.zip</strong></p>

<p style="margin-left: 2em;"><strong>BPEL</strong></p>

<p style="margin-left: 4em;"><strong>myprocess.bpel</strong></p>

<p style="margin-left: 4em;"><strong>myprocess.cbp</strong></p>

<p style="margin-left: 4em;"><strong>myprocess.wsdl</strong></p>

<p style="margin-left: 4em;"><strong>deploy.xml</strong></p>

<p style="margin-left: 4em;"><strong>myschema.xsd</strong></p>

<p>Deploying BPEL package through the management console</p>
<img src="../img/add_bpel.jpg" alt="Add BPEL"/>
<ol>
    <li>In the management console, under Business Processes click Add BPEL. The <em><strong>Add BPEL</strong></em>
        page will appear.
    </li>
    <li>Click <strong>Browse</strong> to locate the file you want to upload.
    </li>
    <li>Click <strong>Upload</strong>. If the BPEL package contains valid processes and adheres to the format, a
        message will appear saying the deployment was successful. If there are compilation failures in process
        definitions, a compilation error message will appear. In case of missing deployment descriptor, 'deploy.xml does
        not exist' message will appear. In this case managment console will not automatically go to <em>Processes</em>
        page or <em>Deployed Packages</em> page.</li>
</ol>

<h2>Managing Deployed Packages</h2>

<p>Click Deployed Packages under Business Processes in the navigation menu.
    The <em><strong>Deployed Packages</strong></em> page will appear.</p>
<img src="../img/packages.jpg" alt="Deployed Packages"/>
<p>This list contains all the BPEL packages deployed in the system and will display business processes in those
    packages.By clicking <em><strong>Undeploy</strong></em> link, users can undeploy the packages available in
    the system.</p>
<p>If user tries to undeploy a package which contains business processes with running process instances, management
    console will warn the user that thare are running process instances. If user really wants, he can undeploy BPEL
    packages with running process instances.</p>

<h2>Managing Deployed Processes</h2>

<p>In the management console, under Business Processes click Processes. The <em><strong>Processes</strong></em> page
    will appear.</p>
<img src="../img/process_list.jpg" alt="Process List"/>
<p>Process list will display IDs of the deployed processes with their version, status and deployed date.
    With this list you can retire and activate processes. You can view detailed description about the process,
    when you click the process id link.
</p>
<p>'Filter Process List' link can be used to expand the process list filter. You can use process list filter to narrow
    down the list of processes using criteria like process name, namespace or deployed date.
    You can order the process list by using properties like name, namespace or version. 

</p>
<img src="../img/process_filter.jpg" alt="Process Filter"/>
<p>Sample Order by filter:</p>
<ul>
    <li>Let's say we want to sort the process list by process definition name. Here if there are processes with same
        name, we want to sort them by their version. The filter for this will be:  'name -version'
</li>
</ul>
<h3>Difference between Active and Retired Processes</h3>
<p>Active processes can be invoked by partners and as a result, new process instances will be created.
    When a process is retired all the running instances of that particular process will behave normally.
    But no new instances will be created from retired processes.
</p>

<h2>Detail View of Deployed Business Process</h2>

<img src="../img/process_details.jpg" alt="Process Details"/>
<p>In the management console, click Processes under Business processes. Then click on any of the process ID links.
    It will display a detailed description about the process including version, status, deployed date,
    container package of that process, total instance, instance summary and syntax highlighted process definition.
</p>
<p>Using the link display in front of the status of the process users can activate or retire that process.</p>

<h2>Managing Process Instances</h2>
<img src="../img/instance_list.jpg" alt="Instance List Page"/>
<p>When you click Instances under Business Processes, <em><strong>Instances</strong></em> page will appear. TThis page
    will display paginated list of currently available process instances in the system.
</p>
<p>The instance list will display ID of the instance with the process id of that instance, current status,
    date started, last active date and actions that can be performed on that instance.
    Users can click on the instance id link to go to the detailed view of that instance and use process id
    link to view the details of the process. Users can use Suspend/Resume, Terminate and Delete links to suspend/resume
    active instance, terminate active instance and to delete instance from the system. Complete and Terminated instances
    can only be deleted and can't perform any other actions on it.
</p>
<p>User can use shortcuts available below the bread crumbs to filter the available instances according to their status.
    Advance Filter link will expand the filter from and users can use that to filter the instance list according to
    process name, process namespace, started date and etc.. If the user want to reset the filter and list all the
    available instances user can use either 'All' shorcut link or 'Reset Filter' link.

</p>
<p>Advance Filter link will expand the filter form and user can use it to narrow down the instace list.
</p>
<img src="../img/instance_filter.jpg" alt="Instance Filter"/>
<p><strong>Using Advance Filtering</strong></p>
<p>Advance Filtering can be used to narrow down the instance by process name, process namespace, status, started date,
    and last active date. And user can order the filtered instance list using Process ID, Name, Version,
    Started Date and Last Active Date.
   </p>
<p>Example:</p>
<ul>
    <li>To get the all the process instances created by process definitions in http://example.com namespace,
        started after 23rd January 2009 6.30 PM and order them in Descending order you should configure filter
        like shown below. When you specify times you have to use 24-hour format <em>"hour:minutes:seconds"</em>.
<br/>
        <img src="../img/sample_ifilter.jpg" alt="Sample Instance Filter"/>
    </li>
    
</ul>

<p> Users can use 'Delete Instances' link to bring the delete instance dialog box and they can specify an instance
    filter to select the instances from the available instances and delete them. 
</p>
<p>Sample instance deletion filters:</p>
<ul>
    <li>To delete all the completed instances: 'status=completed'</li>
    <li>To delete all the instances of process definition {http://example.com}counter-3(3 is the version):
        'pid={http://example.com}counter-3'</li>
</ul>

<h2>Instance Detail Page</h2>
<p>When a user clicks on instance id link at the 'Instances Created' page, instance details page for the instance
    represented by that ID will appear.
</p>
<img src="../img/instance_details.jpg" alt="Instance Details"/>
<p>Instance details page will display information like process id of that instance, status, last active date and event
    information, scope information, variable values and activity information of that instance.
</p>

</body>
</html>


